<!-- 
  ****************************************************************************
  * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_termcap.3x,v 1.33 2017/01/07 19:25:15 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_termcap 3x</TITLE>
<link rev=made href="mailto:bug-ncurses@gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</HEAD>
<BODY>
<H1 class="no-header">curs_termcap 3x</H1>
<PRE>
<STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>                                       <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>PC</STRONG>, <STRONG>UP</STRONG>, <STRONG>BC</STRONG>, <STRONG>ospeed</STRONG>, <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, <STRONG>tgetstr</STRONG>,
       <STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG> - direct <STRONG>curses</STRONG> interface to the terminfo
       capability database


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
       <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>

       <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>PC;</STRONG>
       <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>UP;</STRONG>
       <STRONG>extern</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG>
       <STRONG>extern</STRONG> <STRONG>short</STRONG> <STRONG>ospeed;</STRONG>

       <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*bp,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*name);</STRONG>
       <STRONG>int</STRONG> <STRONG>tgetflag(char</STRONG> <STRONG>*id);</STRONG>
       <STRONG>int</STRONG> <STRONG>tgetnum(char</STRONG> <STRONG>*id);</STRONG>
       <STRONG>char</STRONG> <STRONG>*tgetstr(char</STRONG> <STRONG>*id,</STRONG> <STRONG>char</STRONG> <STRONG>**area);</STRONG>
       <STRONG>char</STRONG> <STRONG>*tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*cap,</STRONG> <STRONG>int</STRONG> <STRONG>col,</STRONG> <STRONG>int</STRONG> <STRONG>row);</STRONG>
       <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*str,</STRONG> <STRONG>int</STRONG> <STRONG>affcnt,</STRONG> <STRONG>int</STRONG> <STRONG>(*putc)(int));</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       These  routines  are included as a conversion aid for pro-
       grams that use the <EM>termcap</EM> library.  Their parameters  are
       the  same and the routines are emulated using the <EM>terminfo</EM>
       database.  Thus, they can only be used to query the  capa-
       bilities  of  entries  for which a terminfo entry has been
       compiled.


</PRE><H3><a name="h3-INITIALIZATION">INITIALIZATION</a></H3><PRE>
       The <STRONG>tgetent</STRONG> routine loads the entry for <EM>name</EM>.  It returns:

          1  on success,

          0  if there is no such entry (or that it is  a  generic
             type,  having  too little information for curses ap-
             plications to run), and

          -1 if the terminfo database could not be found.

       This differs from the <EM>termcap</EM> library in two ways:

          <STRONG>o</STRONG>   The emulation ignores the buffer pointer  <EM>bp</EM>.   The
              <EM>termcap</EM>  library would store a copy of the terminal
              description in the area referenced by this pointer.
              However,  ncurses  stores its terminal descriptions
              in compiled binary form,  which  is  not  the  same
              thing.

          <STRONG>o</STRONG>   There is a difference in return codes.  The <EM>termcap</EM>
              library does not check if the terminal  description
              is  marked  with  the <EM>generic</EM> capability, or if the
              terminal description has cursor-addressing.


</PRE><H3><a name="h3-CAPABILITY-VALUES">CAPABILITY VALUES</a></H3><PRE>
       The <STRONG>tgetflag</STRONG> routine gets the boolean entry for <EM>id</EM>, or ze-
       ro if it is not available.

       The  <STRONG>tgetnum</STRONG>  routine gets the numeric entry for <EM>id</EM>, or -1
       if it is not available.

       The <STRONG>tgetstr</STRONG> routine returns the string entry  for  <EM>id</EM>,  or
       zero  if it is not available.  Use <STRONG>tputs</STRONG> to output the re-
       turned string.  The <EM>area</EM> parameter is used as follows:

          <STRONG>o</STRONG>   It is assumed to be the address of a pointer  to  a
              buffer managed by the calling application.

          <STRONG>o</STRONG>   However,  ncurses checks to ensure that <STRONG>area</STRONG> is not
              NULL, and also that the resulting buffer pointer is
              not  NULL.  If either check fails, the <EM>area</EM> parame-
              ter is ignored.

          <STRONG>o</STRONG>   If the checks succeed, ncurses also copies the  re-
              turn  value  to  the buffer pointed to by <EM>area</EM>, and
              the <EM>area</EM> value will be updated to  point  past  the
              null ending this value.

          <STRONG>o</STRONG>   The return value itself is an address in the termi-
              nal description which is loaded into memory.

       Only the first two characters of the <STRONG>id</STRONG> parameter of <STRONG>tget-</STRONG>
       <STRONG>flag</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetstr</STRONG> are compared in lookups.


</PRE><H3><a name="h3-FORMATTING-CAPABILITIES">FORMATTING CAPABILITIES</a></H3><PRE>
       The  <STRONG>tgoto</STRONG>  routine expands the given capability using the
       parameters.

       <STRONG>o</STRONG>   Because the capability may  have  padding  characters,
           the  output  of <STRONG>tgoto</STRONG> should be passed to <STRONG>tputs</STRONG> rather
           than some other output function such as <STRONG>printf</STRONG>.

       <STRONG>o</STRONG>   While <STRONG>tgoto</STRONG> is assumed to be used for the  two-parame-
           ter  cursor  positioning  capability, termcap applica-
           tions also use it for single-parameter capabilities.

           Doing this shows a quirk in <STRONG>tgoto</STRONG>: most hardware  ter-
           minals  use  cursor addressing with <EM>row</EM> first, but the
           original developers of the termcap interface chose  to
           put  the  <EM>column</EM>  parameter first.  The <STRONG>tgoto</STRONG> function
           swaps the order of parameters.  It does this also  for
           calls  requiring  only  a  single  parameter.  In that
           case, the first parameter is merely a placeholder.

       <STRONG>o</STRONG>   Normally the ncurses library is compiled with terminfo
           support.   In  that case, <STRONG>tgoto</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> (a more
           capable formatter).

       The <STRONG>tputs</STRONG> routine is described  on  the  <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
       manual page.  It can retrieve capabilities by either term-
       cap or terminfo name.


</PRE><H3><a name="h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></H3><PRE>
       The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the ter-
       minfo   entry's   data   for   <STRONG>pad_char</STRONG>,   <STRONG>cursor_up</STRONG>   and
       <STRONG>backspace_if_not_bs</STRONG>, respectively.   <STRONG>UP</STRONG>  is  not  used  by
       ncurses.  <STRONG>PC</STRONG> is used in the <STRONG>tdelay_output</STRONG> function.  <STRONG>BC</STRONG> is
       used in the <STRONG>tgoto</STRONG> emulation.  The variable <STRONG>ospeed</STRONG>  is  set
       by ncurses in a system-specific coding to reflect the ter-
       minal speed.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       Except where explicitly noted, routines that return an in-
       teger  return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 only specifies
       "an integer value other than <STRONG>ERR</STRONG>") upon successful comple-
       tion.

       Routines that return pointers return <STRONG>NULL</STRONG> on error.


</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE>
       If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>ca</STRONG> or any other parameterized
       string, be aware that it will be returned in terminfo  no-
       tation, not the older and not-quite-compatible termcap no-
       tation.  This will not cause problems if all you  do  with
       it  is  call  <STRONG>tgoto</STRONG>  or <STRONG>tparm</STRONG>, which both expand terminfo-
       style strings as terminfo.  (The <STRONG>tgoto</STRONG> function,  if  con-
       figured  to  support  termcap, will check if the string is
       indeed terminfo-style by looking for  "%p"  parameters  or
       "$&lt;..&gt;"  delays,  and invoke a termcap-style parser if the
       string does not appear to be terminfo).

       Because terminfo conventions for representing  padding  in
       string  capabilities  differ  from termcap's, <STRONG>tputs("50");</STRONG>
       will put out a literal "50" rather than  busy-waiting  for
       50 milliseconds.  Cope with it.

       Note  that termcap has nothing analogous to terminfo's <STRONG>sgr</STRONG>
       string.  One consequence of this is that termcap  applica-
       tions  assume me (terminfo <STRONG>sgr0</STRONG>) does not reset the alter-
       nate character set.  This implementation checks  for,  and
       modifies the data shown to the termcap interface to accom-
       modate termcap's limitation in this respect.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       The XSI Curses standard, Issue  4  describes  these  func-
       tions.   However,  they are marked TO BE WITHDRAWN and may
       be removed in future versions.

       Neither the XSI Curses standard nor  the  SVr4  man  pages
       documented  the return values of <STRONG>tgetent</STRONG> correctly, though
       all three were in fact returned ever since SVr1.  In  par-
       ticular,  an  omission in the XSI Curses documentation has
       been misinterpreted to mean that  <STRONG>tgetent</STRONG>  returns  <STRONG>OK</STRONG>  or
       <STRONG>ERR</STRONG>.  Because the purpose of these functions is to provide
       compatibility with the <EM>termcap</EM> library, that is  a  defect
       in XCurses, Issue 4, Version 2 rather than in ncurses.

       External  variables  are  provided  for support of certain
       termcap applications.  However, termcap applications'  use
       of those variables is poorly documented, e.g., not distin-
       guishing between input and output.   In  particular,  some
       applications are reported to declare and/or modify <STRONG>ospeed</STRONG>.

       The  comment  that only the first two characters of the <STRONG>id</STRONG>
       parameter are used escapes  many  application  developers.
       The  original  BSD  4.2  termcap  library  (and historical
       relics thereof) did not require a trailing null NUL on the
       parameter  name  passed  to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG> and <STRONG>tgetflag</STRONG>.
       Some applications assume that the termcap  interface  does
       not require the trailing NUL for the parameter name.  Tak-
       ing into account these issues:

       <STRONG>o</STRONG>   As a special case, <STRONG>tgetflag</STRONG> matched against a  single-
           character  identifier  provided that was at the end of
           the terminal description.  You should  not  rely  upon
           this  behavior in portable programs.  This implementa-
           tion disallows matches against single-character  capa-
           bility names.

       <STRONG>o</STRONG>   This  implementation  disallows matches by the termcap
           interface against extended capability names which  are
           longer than two characters.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>.

       http://invisible-island.net/ncurses/tctest.html



                                                       <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-INITIALIZATION">INITIALIZATION</a></li>
<li><a href="#h3-CAPABILITY-VALUES">CAPABILITY VALUES</a></li>
<li><a href="#h3-FORMATTING-CAPABILITIES">FORMATTING CAPABILITIES</a></li>
<li><a href="#h3-GLOBAL-VARIABLES">GLOBAL VARIABLES</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-BUGS">BUGS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
